BeginRelinquishFocus

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods / ODPart

BeginRelinquishFocus
The BeginRelinquishFocus method should return a Boolean value that indicates whether this part is willing to relinquish the requested focus and should prepare this part to do so.
ODBoolean BeginRelinquishFocus (in ODTypeToken focus,
                                in ODFrame ownerFrame, 
                                in ODFrame proposedFrame);
focus
A tokenized string representing the focus type to be relinquished, expressed as a 32-bit value.
ownerFrame
A reference to a display frame that currently possesses the focus.
proposedFrame
A reference to a frame requesting ownership of the focus.
return value
kODTrue if this part is willing to relinquish the requested focus, otherwise kODFalse.

DISCUSSION
The focus parameter must be the tokenized form of one of the focus constants (kODClipboardFocus, kODKeyFocus, kODMenuFocus, kODModalFocus, kODMouseFocus, kODScrollingFocus, or kODSelectionFocus) or the tokenized form of a part-specific focus type. You can call the session object's Tokenize method to obtain a token corresponding to one of these constants.
OpenDoc calls this method when ownership of the specified focus is requested and this part is the current owner. Upon receiving this call, this part decides whether it can relinquish the specified focus. Each part has part-specific requirements that must be met before it can relinquish a focus. If these requirements are met, this part should be ready to relinquish the focus.
Your part's BeginRelinquishFocus method should return either kODTrue or kODFalse, based on the type of focus and the identities of the frames (current and proposed focus owners) passed in. In most cases, your method should return kODTrue. However, your method might return kODFalse, for example, if your part is displaying a modal dialog box and another part is requesting the modal focus. In that case, because your part does not want to yield the modal focus until its modal dialog box closes, your method should return kODFalse. In situations when your method does return kODFalse, then your part's AbortRelinquishFocus method does not need to take any action.
Your part's BeginRelinquishFocus method should also ensure that, during the process of relinquishing the specified focus and before your part's CommitRelinquishFocus method is called, your part does not enter a state where the focus cannot be relinquished.

OVERRIDING
When you subclass ODPart, you must override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.

EXCEPTIONS

kODErrInvalidFrame
The specified owner frame is not a display frame of this part.

SEE ALSO
The ODFocusType type (page 889).
The ODTypeToken type (page 877).
The ODPart::AbortRelinquishFocus method (page 475).
The ODPart::CommitRelinquishFocus method (page 488).
The ODSession::Tokenize method (page 622).
"The BeginRelinquishFocus Method" on page 90 in OpenDoc Cookbook.
Table 2-1 on page 89 in OpenDoc Programmer's Guide.
"Requesting Foci" on page 208 in OpenDoc Programmer's Guide.
"Acquiring and Relinquishing the Modal Focus" on page 232 in OpenDoc Programmer's Guide.
"Creating a Focus Module" on page 448 in OpenDoc Programmer's Guide.